import { PackageManagerTabs } from '@theme';

# Modern.js Module

This section introduces how to migrate a project using Modern.js Module to Rslib.

## Adapt package.json

`Rslib` has a minimal dependency footprint. For the basic functionality you only need the package `@rslib/core`.

You can create a new Rslib project by following the [Quick start](/guide/start/quick-start) to see the `package.json` file. Then update your existing `package.json` file like below:

- Remove the fields `main`, `lint-staged`, `simple-git-hooks`, `sideEffects` and `publishConfig`
- Change the `types` field from `./dist/types/index.d.ts` to `./dist/index.d.ts`
- Change the `module` field from `./dist/es/index.js` to `./dist/index.js`
- Remove the scripts fields `prepare`, `build:watch`, `reset`, `change`, `bump`, `pre`, `change-status`, `gen-release-note`, `release`, `new`, `upgrade`
- Change the script `build` from `modern build` to `rslib build`
- Change the script `dev` from `modern dev` to `rslib build --watch`
- Change the script `lint` name to `check` and keep the value
- Add a new script `format` with the value `biome format --write`
- Add the script `test` with the value `vitest run`
- Add the field `exports` (object)
  - Add the field `"."` (object)
  - Add the fields `"types": "./dist/index.d.ts"` and `"import": "./dist/index.js"`
- Add the field `files` with the value `["dist"]`
- Depending on your configuration and use-case the `devDependencies` can vary
  - It is important to replace `@modern-js/module-tools` with `@rslib/core`
  - We do not need `rimraf`, `lint-staged` and `simple-git-hooks` anymore for starters
- Copy over your required `dependencies` and `peerDependencies` if needed

Your `package.json` should look something like this:

```json title="package.json"
{
  "name": "rslib",
  "version": "1.0.0",
  "type": "module",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    }
  },
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "files": ["dist"],
  "scripts": {
    "build": "rslib build",
    "check": "biome check --write",
    "dev": "rslib build --watch",
    "format": "biome format --write",
    "test": "vitest run"
  },
  "devDependencies": {
    "@biomejs/biome": "^2.0.0",
    "@rslib/core": "^0.1.3",
    "typescript": "^5.6.3",
    "vitest": "^2.1.8"
  },
  "peerDependencies": {},
  "dependencies": {}
}
```

## Adapt bundler config

Now we have a clean slate to work with. We will continue with the `Rslib` configuration. It follows the same pattern as all `Rs*` projects. Since this step is very unique for every environment, below is an basic example:

Replace your `modern.config.ts` with a `rslib.config.ts`:

```js title="rslib.config.ts"
import { defineConfig } from '@rslib/core';

export default defineConfig({
  source: {
    entry: {
      index: ['./src/**'],
    },
  },
  lib: [
    {
      bundle: false,
      dts: true,
      format: 'esm',
    },
  ],
});
```

## TypeScript declaration

If you use TypeScript in your `Modern.js Module` and need to generate declaration files, add the following changes:

```js title="rslib.config.ts"
import { defineConfig } from '@rslib/core';

export default defineConfig({
  //...
  lib: [
    {
      //...
      dts: true,
    },
  ],
});
```

## React

If you use React in your `Modern.js Module`, add the following changes:

```js title="rslib.config.ts"
import { defineConfig } from '@rslib/core';
// Quick tip: You can use all Rsbuild plugins here since they are compatible with Rslib
import { pluginReact } from '@rsbuild/plugin-react';

export default defineConfig({
  //...
  output: {
    target: 'web',
  },
  plugins: [pluginReact()],
});
```

In addition, you have to install the `@rsbuild/plugin-react` package as `devDependencies`.

<PackageManagerTabs command="add @rsbuild/plugin-react -D" />

## Sass

If you use Sass in your `Modern.js Module`, add the following changes:

```js title="rslib.config.ts"
import { defineConfig } from '@rslib/core';
// Quick tip: You can use all Rsbuild plugins here since they are compatible with Rslib
import { pluginSass } from '@rsbuild/plugin-sass';

export default defineConfig({
  //...
  plugins: [pluginSass()],
});
```

In addition, you have to install the `@rsbuild/plugin-sass` package as `devDependencies`.

<PackageManagerTabs command="add @rsbuild/plugin-sass -D" />

If you run TypeScript together with Sass, you might run into declaration files generation errors. This can be resolved by adding a `env.d.ts` file in your `/src` directory.

```ts title="src/env.d.ts"
declare module '*.scss' {
  const content: { [className: string]: string };
  export default content;
}
```

or

```ts title="src/env.d.ts"
/// <reference types="@rslib/core/types" />
```

## CSS Modules

If you use CSS Modules in your `Modern.js Module`, add the following changes:

```js title="rslib.config.ts"
import { defineConfig } from '@rslib/core';
import { pluginSass } from '@rsbuild/plugin-sass';

export default defineConfig({
  lib: [
    {
      //...
      output: {
        cssModules: {
          // the CSS Modules options are 1:1 the same as in the official "css-modules" package
          localIdentName: '[local]--[hash:base64:5]',
        },
      },
    },
  ],
  plugins: [pluginSass()],
});
```

## Contents supplement

This migration doc is contributed by community user [YanPes](https://github.com/YanPes). Much appreciation for his contribution!
